Microsoft Dynamics AX 2009 : The Application Integration Framework (part 7) - Sending One-Way Requests from Dynamics AX

Sending One-Way Requests from Dynamics AX

When you think about exchanging business documents electronically with your trading partners, you need to accept that it might not be realistic to assume that your trading partners’ applications will always be online and ready to receive your messages. With some partners, building more robust, loosely coupled integrations using one-way messages might be a better solution.

AIF provides APIs to send unsolicited one-way messages by using Dynamics AX services and the AIF infrastructure (e.g., channels and endpoints). The Dynamics AX client features Send Electronically buttons on several forms that allow you to transmit business documents (such as invoices) as unsolicited one-way messages through AIF channels to AIF endpoints. Dynamics AX is aware of only the AIF channel it needs to send the message to (i.e., the next hop); it doesn’t know the final destination of the message. Moreover, Dynamics AX doesn’t rely on any external document schema definitions to be provided by the remote receiving application; it uses its own format instead—the same Axd<Document> class-based XSDs that are also used as data contracts for published Dynamics AX services.

Implementing unsolicited messages exchanges requires the following two steps:

• Implementing a trigger for transmission (design time)
  
  
• Configuring transmission mechanisms (admin time)
  
  

Implementing a Trigger for Transmission

You can implement a trigger for transmission by using either the AIF Send API or the AxdSend API.

AIF Send API

The Send API in AIF features a set of methods that can be used to send unsolicited one-way messages from Dynamics AX to AIF channels, through which the consumers can pick up the messages. This API sends a single message; the body of the message is the XML that is generated by invoking the service operation read of the AIF document service referenced by serviceClassId (it must reference a class that derives from AifDocumentService) with the parameter entityKey.

To see a working example of how you can use this API, look at the code behind the method clicked for the button SendXmlOriginal on the form CustInvoiceJournal. The API methods are defined on the class AifSendService and include the method submitDefault.

public static void submitDefault(
    AifServiceClassId serviceClassId,
    AifEntityKey entityKey,
    AifConstraintList constraintList,
    AifSendMode sendMode,
    AifPropertyBag propertyBag = connull(),
    AifProcessingMode processingMode = AifProcessingMode::Sequential,
    AifConversationId conversationId = #NoConversationId
)

The two optional parameters in the preceding signature, processingMode and conversationId, are new in Dynamics AX 2009. They allow you to leverage the newly introduced parallel message processing feature for asynchronous adapters:

• processingMode Specifies whether messages can be moved from the AIF outbound processing queue to the AIF gateway queue in parallel (AifProcessingMode:: Parallel) or whether first in first out (FIFO) order must be enforced for all messages (AifProcessingMode::Sequential).

• conversationId If specified, moves from the AIF outbound processing queue to the AIF gateway queue in FIFO order, relative to all other messages with the same conversationId. The order relative to all other messages with other conversationIds isn’t guaranteed.

AxdSend API

The AxdSend API provides functionality to send unsolicited one-way messages for which the user needs to select AIF endpoints dynamically at run time or in which the message body contains more than a single entity. The user dynamically selects the exact range of entities, such as a range of ledger accounts, at run time. This feature has been implemented for several Dynamics AX document services, including AxdChartOfAccounts and AxdPricelist.

The AxdSend framework provides default dialog boxes for selecting endpoints and entity ranges and allows the generation of XML documents with multiple records. The framework allows you to provide specific dialog boxes for documents that need more user input than the default dialog box provides.

The default dialog box includes an endpoint drop-down list and, optionally, a Select button to open the standard query form. The query is retrieved from the Axd<Document> class the caller specifies. Many endpoints can be configured in the AIF, but only a few are allowed to receive the current document. The lookup shows only the endpoints that are valid for the document, complying with the constraint set up for the service operation read for the current document.

The framework requires minimal coding to support a new document. If a document requires you to simply select an endpoint and fill out a query range, most of the functionality is provided by the framework, without requiring additional code.

The standard dialog box for the AxdSend framework is shown in Figure 6.

Figure 6. Send Document Electronically dialog box for Chart of accounts

If a document requires a more specific dialog box, you simply inherit the AxdSend class and provide the necessary user interface interaction to the dialog box method. In the following code example, an extra field has been added to the dialog box. You simply add one line of code (shown in bold in the following code from the AxdSendChartOfAccounts class) to implement parmShowDocPurpose from the AxdSend class and to make this field appear on the dialog box.

static public void main(Args args)
{
   AxdSendChartofAccounts axdSendChartofAccounts ;
   AifConstraintList aifConstraintList;
   AifConstraint aifConstraint;
   ;
   axdSendChartofAccounts = new AxdSendChartofAccounts();
   aifConstraintList = new AifConstraintList();
   aifConstraint = new AifConstraint();

   aifConstraint.parmType(AifConstraintType::NoConstraint);
   aifConstraintList.addConstraint(aifConstraint);
axdSendChartofAccounts.parmShowDocPurpose(true) ;

    axdSendChartofAccounts.sendMultipleDocuments(classnum(AxdChartOfAccounts),A
ifSendMode::Async,aifConstraintList) ;

}

					  

Sorting isn’t supported in the AxdSend framework, and the query structure is locked to ensure that the resulting query matches the query defined by the XML document framework. This need for matching is why the AxdSend class enforces these sorting and structure limitations. The query dialog box shows only the fields on the top-level tables because of the mechanics of queries with an outer join predicate. The result set will likely be different from what would be expected from a user perspective. For example, restrictions on inner data sources filter only these data sources, not the data sources that contain them. The restrictions are imposed on the user interface to match the restrictions on the query when using the document service’s operation find.